gh-138072: Small clarifications and phrasing improvements to asyncio HOWTO #138073
Conversation
anordin95
requested review from
1st1,
asvetlov,
kumaraditya303 and
willingc
as code owners
bedevere-app
bot
added
awaiting review
docs
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
|
I think all requested changes have been addressed in this PR, besides modifications to the For ease of reference, the style guide says: "In the Python documentation, the use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule.". Additionally, I think the use of "preferable" above implies there can be reasonable cases that ignore this guidance. I personally prefer the titles as they are now, for the reasons enumerated here. With that in mind, I wonder if leaving them as is would be amenable for folks? |
|
Please do rename them to "Awaiting tasks" and "Awaiting coroutines".
That's referring to the The next sentence of the devguide:
Well, the rest is already in sentence case, let's stick to it. |
|
For reference, I interpreted the style guide as providing some leeway and more generally I think it can make sense to sometimes ignore strict adherence to style guides, in this case, for the sake of content/flow. Either way, it seems my arguments fell short and failed to sway minds! I'll go ahead and change the section titles as requested. P.S. The same idea regarding |
|
Hey folks, I believe all comments have now been addressed. @willingc, @kumaraditya303, @ZeroIntensity would you mind taking another pass? |
| to specify the event loop. | ||
| Since there's only one event loop (in each thread), :mod:`!asyncio` takes | ||
| care of associating the task with the event loop for you. | ||
| As such, there's no need to specify the event loop. |
There was a problem hiding this comment.
| As such, there's no need to specify the event loop. | |
| As such, there's no need to specify the event loop when calling ``asyncio``. |
There was a problem hiding this comment.
I think it's a bit redundant to mention asyncio again given the prior sentence also does.
| Then, the event loop needs to manage its internal state and work through | ||
| its processing logic to resume the next job. | ||
| That might sound minor, but in a large program with many ``await``\ s, that | ||
| overhead can add up to a meaningful performance drag. |
There was a problem hiding this comment.
I think "meaningful" has a positive connotation here, which we don't want. How about this?
| overhead can add up to a meaningful performance drag. | |
| overhead can add up to a major performance drag. |
There was a problem hiding this comment.
Just to make sure I understand, the concern is that "meaningful" has a positive connotation, which may confuse a reader into thinking we're saying a "performance drag" is a good thing, yeah?
I think "major" would be overstating the effect. The goal was to describe something that's non-trivial or non-negligible. For what it's worth, I think "meaningful" can be used either way e.g. "a meaningful decline in sales", "a meaningful improvement in test scores", etc. Regardless, would switching to "non-trivial" be amenable?
📚 Documentation preview 📚: https://cpython-previews--138073.org.readthedocs.build/en/138073/howto/a-conceptual-overview-of-asyncio.html#a-conceptual-overview-of-asyncio